home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
FishMarket 1.0
/
FishMarket v1.0.iso
/
fishies
/
201-225
/
disk_202
/
vlt
/
docs
/
rexx.zoo
/
rexxarplib.doc
next >
Wrap
Text File
|
1989-05-04
|
25KB
|
563 lines
RexxArpLib.Library Version 2.0
==============================
Copyright (C) 1988
by
W.G.J. Langeveld
Originally, this library was supposed to be an ARexx interface to the
ARP library. However, although it indeed interfaces to some of the ARP
functions, it has become much more of an interface to various Intuition
functions. I have considered renaming the library to something else, but by now
everyone refers to it by this name, so I'll leave it like it is.
Version 2.0 is pretty much the final version. The library has grown
considerably since the first release, and it is about as big as a library should
ever get. If I find the need for a lot of other functions, they'll have to go
into a different library.
The library contains over 50 functions now. One is Charlie's famous ARP
file requester, another is a simple combination string/boolean requester that
does auto-everything. All you have to do is specify the strings you want it to
display. Then there are environment variable things, and a simple message window
you can keep hanging around. On popular request, there is now a wildcard
expander (not to be confused with a 'directory' function!) that uses the new Rexx
Variables Interface (RVI).
The major new things though, are the interface routines to Intuition.
You can now open screens and windows, add boolean and string gadgets to them as
well as menus, draw lines and areas and circles and whatever. You can make your
gadgets, menus, and windows send messages to wherever you like and you can
format those messages, though they have to ARexx messages, in any way you like,
using any information that's currently available. All this is rather hard to
explain. You'll really have to play with it and look at some examples.
As usual, this stuff is NOT public domain, but freely distributable.
So have fun!
Willy.
The functions are listed below.
--------------------------------------------------------------------------------
GetFile
=======
Calling sequence:
result = GetFile(x, y, pathname, filename, hailstring, publicscreen)
x = x coordinate of top-left corner of requester.
y = y coordinate of top-left corner of requester.
pathname = Default path name, first path name to be searched.
filename = Default file name.
hailstring = User instruction string.
result = The selected path/file name
publicscreen = Name of a public screen (optional).
All arguments are optional, but the order is fixed. Therefore if only
the second or third argument is specified, it needs to be prefixed by
sufficient commas.
The selected path concatenated with the selected file name are
returned as 'result'. Notice, that the result is not necessarily an existing
file. It is up to the user to ascertain that the result is suitable for his
purposes. If the user hits "CANCEL", the result is an empty string. Notice
that another way the result comes out to be empty is when the user leaves the
requester hitting "OKAY" when both the path and file string gadgets are
empty.
If 'publicscreen' is specified, the function will try to find the screen
of that name. If it is set up properly, the requester will open on that
screen. If not, the requester will appear on the Workbench. The mechanism that
is currently used for this is subject to change.
Request
=======
Calling sequence:
result = Request(x, y, prompts, string, okaytext, canceltext, publicscreen)
x = x coordinate of top-left corner of requester.
y = y coordinate of top-left corner of requester.
prompts = A string which will be displayed above any gadgets.
Any embedded '\' characters will be treated as a line
break.
string = The default string to be displayed in a string gadget.
If omitted, no string gadget will be provided.
okaytext = The text to be used for an Okay gadget.
If omitted, no okay gadget will be provided.
canceltext = The text to be used for a Cancel gadget.
If omitted, no cancel gadget will be provided.
publicscreen = Name of a public screen (optional).
All arguments are optional, but the order is fixed. Therefore if
only the second or third argument is specified, it needs to be prefixed by
sufficient commas.
If a string gadget is present, but no okay gadget, the string
will be returned after modification by the user in result when the user
hits <return>.
If both a string gadget and an okay gadget are present, the string
will be returned in result only when the user clicks on the okay gadget.
If no string gadget is present, clicking of the okay gadget (if
present) will cause the return in result of the string "OKAY".
In any case, if the user clicks either the cancel gadget or the
close gadget, an empty string will be returned. Notice that another way the
result comes out to be empty is when the user leaves the requester hitting
"OKAY" when the string gadget is empty.
If 'publicscreen' is specified, the function will try to find the screen
of that name. If it is set up properly, the requester will open on that
screen. If not, the requester will appear on the Workbench. The mechanism that
is currently used for this is subject to change.
PostMsg
=======
This function sets up a window with text. It returns immediately to
the caller. Subsequent calls will erase lines and fill them with new text.
If a line has zero length, the line will NOT be erased. This has the advantage
that you can change the text in a line without redisplaying text in another
line. It has the disadvantage that in order to erase lines, you have to
specify at least a single space for each line you want to erase.
The window will remain open, until a call is made with too few arguments.
This is NOT a reentrant function: there is only one window pointer, and
subsequent calls by ANY REXX process will affect the window.
Calling sequence:
result = PostMsg(x, y, strings, publicscreen)
x = x coordinate of top-left corner of requester.
y = y coordinate of top-left corner of requester.
string = A string which will be displayed above any gadgets.
Any embedded '\' characters will be treated as a line
break.
result = 1 for success, 0 otherwise.
publicscreen = Name of a public screen (optional).
All arguments are optional, but the order is fixed. Therefore if
only the second or third argument is specified, it needs to be prefixed by
sufficient commas.
Examples:
Postmsg(50, 50, "This is line 1\This is line 2")
will cause a window to appear with two lines of text. A subsequent call
Postmsg(50, 50, "\This is a new line 2")
will cause the second line of the window to be replaced by the new text. The
construct:
PostMsg(50, 50, " \")
will erase the first line but leave the second one alone (notice the space).
If too few arguments are specified, this function will cause the
window to be closed.
If 'publicscreen' is specified, the function will try to find the screen
of that name. If it is set up properly, the requester will open on that
screen. If not, the requester will appear on the Workbench. The mechanism that
is currently used for this is subject to change.
Getenv
======
Calling sequence:
result = Getenv(variable)
variable = Environment variable.
result = The value of the environment variable.
This function gets the value of an environment variable. If the
variable does not exist, an empty string will be returned.
Setenv
======
Calling sequence:
result = Setenv(variable, valuestring)
variable = Environment variable.
valuestring = The new value for the environment variable.
result = Always 1.
This function (creates and) sets the environment variable to a
a (new) value. If 'valuestring' is missing, the function will remove the
environment variable.
ScreenToBack, ScreenToFront
===========================
These functions depth arrange screens. If no argument is specified,
the screen operated on is the Workbench screen. If the name of a public screen
is specified, it will be affected.
Calling sequence:
result = screentoback(publicscreen)
result = screentofront(publicscreen)
publicscreen = Name of a public screen (optional).
The argument is optional. If 'publicscreen' is specified, the function
will try to find the screen of that name. If it is set up properly, the screen
will be moved to the back/front. If not, the function will operate on the
Workbench screen. The mechanism that is currently used for this is subject to
change.
ScreenRows, ScreenCols, ScreenLace
==================================
These functions retrieve info about screens. If no argument is
specified, the screen operated on is the Workbench screen. If the name of a
public screen is specified, it will be used.
Calling sequence:
result = ScreenRows(publicscreen) /* return number of rows */
result = ScreenCols(publicscreen) /* return number of columns */
result = ScreenLace(publicscreen) /* return interlace */
publicscreen = Name of a public screen (optional).
These functions retrieve the number of rows and columns in pixels.
The function screenlace() returns 0 if the screen is not interlaced, and 1
if it is. The function returns -1 if the information could not be found.
The argument is optional. If 'publicscreen' is specified, the function
will try to find the screen of that name. If it is set up properly, information
about the screen will be returned. If not, the function will operate on the
Workbench screen. The mechanism that is currently used for this is subject to
change.
OpenScreen, CloseScreen
=======================
These functions allow you to open public custom screens.
Calling sequence:
result = OpenScreen(topedge, depth, modes, defaulttitle, publicscreen)
result = CloseScreen(publicscreen)
topedge = Y coordinate of top edge of the screen.
depth = Number of bitplanes.
modes = Viewmodes and type of screen. The currently supported
viewmodes are "HIRES", "LACE", and "HAM". The one
currently supported type is "SCREENBEHIND".
defaulttitle = Default title for the screen title bar.
publicscreen = Name of a public screen (optional).
result = 0 on failure, 1 on success.
The last argument is required, therefore you must supply sufficient
commas and a name for the public screen to be created/closed. With openscreen,
leaving out any of the other arguments will cause defaults to be used. They are
topedge = 0, depth = 2, modes = 0 (meaning LORES, no LACE), and no default
title. This is equivalent to specifying 0 for all arguments (a depth of 0 is
illegal and will be changed to 2). All created screens are CUSTOM screens.
The mechanism that is currently used for public screens is subject to
change.
***NOTE: It is perfectly possible to apply closescreen() to another
application's custom screen (if it is public, using the same conventions as
used here). If you attempt this, a software failure is almost guaranteed. Only
use closescreen() on screens you created using openscreen()!
FileList
========
This function does ARP pattern matching. Given a pattern, it will
return all files and/or directories matching the pattern.
Calling sequence:
number = FileList(pattern, files, flags)
pattern = a search pattern using ARP wildcards.
files = the NAME of a stem variable to be created.
flags = Directories - directories only. Files - files only.
number = the number of files matching the pattern.
When files with names matching the pattern are found, a stem variable
with the name given by 'files' is created in the current Rexx context. It has
fields 1, 2, ...., <number> containing the names of the files. The last argument
is optional: when an F is specified, only files are listed. When a D is specified
only directories are listed. Example: a simple directory program looks like
/* Directory program, list everything */
arg pattern
if pattern = "" then pattern = "*"
numfils = FileList(pattern, myfilelist)
do i = 1 to numfils; say myfilelist.i; end
exit
CreateHost
==========
This function allows you to create a single window with gadgets, menus,
text, graphics, etc. Of course, multiple copies of the function may be started
up to create more windows, but each must have a unique 'controlport'. This
function should be started up asynchronously, using runwsh, and one should wait
for the 'controlport' to appear using e.g. WaitForPort.
Calling sequence:
runwsh 'call CreateHost(controlport, notifyport, publicscreen)'
controlport = Name of the message port this window should listen to.
notifyport = Name of the message port that should be notified when
an IDCMP event occurs.
publicscreen = Name of a public screen (optional).
When the function is first called, it will open a message port with the
name given by "controlport". The function will then wait for commands coming in
through this port. This may be accomplished using one of many intuition
functions, as explained later. One of the first commands should be to open the
associated window by calling OpenWindow (see later). It will then open a window
as specified in the OpenWindow call. If any message arrives through the IDCMP of
this window, a REXX message will be sent to the port specified as "notifyport"
which either you should set up in your rexx macro for this purpose, or should be
an otherwise existing rexx message port belonging to another process. In the
case you set up your own port, make sure the message is replied to after having
been retrieved and examined. If the notifyport does not exist, no message will
be sent. The window can be closed by the rexx macro by calling the function
CloseWindow (see later). On startup, the notify port is the same for all classes
of messages. This can be changed using the SetNotify() function, see later.
The last argument is optional. If 'publicscreen' is specified, the
function will try to find the screen of that name. If it is set up properly, the
window will be opened on it. If not, the window will be opened on the Workbench
screen. The mechanism that is currently used for this is subject to change.
Supported Intuition (and other) functions with createhost
=========================================================
The following functions are implemented as CreateHost functions. The
first argument is always the name of the control port of the host that is
supposed to execute the command. A little secret: you can send commands
*directly* to the controlport also by constructs like "Address controlport
commandname". However, this only works for commands without further arguments.
For example, from WShell, "address controlport CloseWindow" is equivalent to
"call CloseWindow(controlport)". This can come in incredibly handy at times.
For example, when you want command hosts to send message to themselves: you
can tell a host to send IDCMP events of class CLOSEWINDOW to itself...
Boggles the mind yet? Read on...
call ActivateGadget(controlport, gadgetid)
Tries to activate a string gadget with id 'gadgetid'.
call ActivateWindow(controlport)
call AreaCircle(controlport, xcenter, ycenter, radius)
call AreaDraw(controlport, x, y)
Only 100 vertices are currently allowed before each AreaEnd().
call AreaEllipse(controlport, xcenter, ycenter, radius1, radius2)
call AreaEnd(controlport)
Only 100 vertices are currently allowed before each AreaEnd().
call AreaMove(controlport, x, y)
Only 100 vertices are currently allowed before each AreaEnd().
call AddGadget(controlport, x, y, gadgetid, gadgettext, messagetext, hsize)
If hsize is specified, this call creates a string gadget of that
horizontal size and gadgettext is the default string. If hsize is
not specified, this call creates an autosizing boolean gadget, where
the text in gadgettext is displayed. In both cases, the string in
messagetext is sent to controlport (see also under OpenWindow). As
usual, the gadgettext for boolean gadgets may contain \ characters
to cause multiple lines of text (See e.g. PostMsg()).
call AddItem(controlport, itemname, message, commandchar, mutualexclude, flag)
Add a new item with name 'itemname'. Optionally, you may specify a
command key abbreviation (right-Amiga 'commandchar') and a mutual exclude
mask. See Intuition manual. A special value of the mutual exclude mask
is -1: this means that the item will be toggle selectable. If the flag
argument is present (any value), the item will be on the same line as
the previous item.
See also AddMenu(), AddSubItem(), FreeMenu(), SetItem().
call AddMenu(controlport, menuname)
Add a new menu with name 'menuname'. See also AddItem(), AddSubItem(),
FreeMenu(), SetItem().
call AddSubItem(controlport,itemname,message,commandchar,mutualexclude,flag)
Add a new subitem with name 'itemname'. Optionally, you may specify a
command key abbreviation (right-Amiga 'commandchar') and a mutual exclude
mask. See Intuition manual. A special value of the mutual exclude mask
is -1: this means that the item will be toggle selectable. If the flag
argument is present (any value), the subitem will be on the same line as
the previous item. See also AddMenu(), AddItem(), FreeMenu(), SetItem().
call BackFill(controlport)
This is not an intuition function. See OpenWindow().
call CloseWindow(controlport)
This function closes the window, deallocates all resources and causes
the host to exit. CloseWindow(), Exit(), Quit() and Stop() are identical.
call Draw(controlport, x, y)
call DrawCircle(controlport, xcenter, ycenter, radius)
call DrawEllipse(controlport, xcenter, ycenter, radius1, radius2)
call Exit(controlport)
This function closes the window, deallocates all resources and causes
the host to exit. CloseWindow(), Exit(), Quit() and Stop() are identical.
call Flood(controlport, mode, x, y)
If mode is 0, the flood continues until pixels of the outline pen
color are found. If the mode is 1, the flood continues until pixels
of a different color than the pixel at x, y are found.
call FreeMenu(controlport)
Gets rid of any attached menu.
call ModifyHost(controlport, IDCMPclass, messagestring)
This function allows you to set the message string that is sent to
the notifyport for a particular class of IDCMP events. See OpenWindow.
call Move(controlport, x, y)
call OpenWindow(controlport, leftedge, topedge, width, height,
idcmp, flags, title)
width and height may be set to 0 to get the maximum size of the window.
idcmp is a string that specifies the IDCMP for the window. Supported are:
IDCMP message | default arg[0]
--------------------+-------------------
"CLOSEWINDOW" | "%l"
"MOUSEBUTTONS" | "%l"
"GADGETUP" | <its string>
"GADGETDOWN" | <its string>
"MENUPICK" | "%l"
"NEWSIZE" | "%l"
"VANILLAKEY" | "%l"
"RAWKEY" | "%l"
"NEWPREFS" | "%l"
"DISKINSERTED" | "%l"
"DISKREMOVED" | "%l"
"ACTIVEWINDOW" | "%l"
"INACTIVEWINDOW" | "%l"
"REFRESHWINDOW" | "%l"
"MOUSEMOVE" | "%l"
Any number of these may be specified in the OpenWindow call, by conca-
tenation. When any of these messages arrives at the IDCMP, a REXX
message is created with a particular string in Arg[0]. This string is
by default the one given in the table above, after substitution has
taken place for any two-character sequence starting with '%'.
The following substitutions will be made:
%% : A single % sign
%a : Vanillakeys: code is interpreted as an ASCII character.
%b : Buttons: SELECTDOWN, SELECTUP, MENUDOWN, MENUUP.
%c : Code: is given as an integer.
%d : Gadgets: the gadget id.
%g : Gadgets: the string inside a string gadget goes here.
%h : Newsize: the window height.
%i : Menus: the item number.
%l : "Literal": the name of the IDCMP class.
%m : Menus: the menu number.
%q : Qualifier: is given as an integer.
%s : Menus: the sub-item number.
%t : Time: the number of seconds since January 1 1980.
%w : Newsize: the window width.
%x : Mouse: the X position of the mouse pointer.
%y : Mouse: the Y position of the mouse pointer.
%0-%15 : which Arg to use.
For example, if the message string of some gadget is
"Mouse is %x, %y%3gadget string is %g"
the following might be sent to the notifyport in Arg[0] when someone
hits return in that gadget, after typing "This is a test":
Mouse is 320, 200
while Arg[3] of the Rexx message would contain the string:
gadget string is This is a test
The default string for non-gadgets/menus is "%l", which means that they
only report their name. For example, if one would click in the window,
one would only receive a message with "MOUSEBUTTONS" in Arg[0]. However,
all arguments of the message that will be sent to the notifyport may be
changed using the ModifyHost() call, see there. Any of the escape
sequences above may be used in any string. Obviously, sometimes
particular sequences may not be very appropriate for certain uses.
'flags' specifies the various window flags. Currently supported are:
"WINDOWCLOSE", "WINDOWSIZING" (and "SIZEBRIGHT", "SIZEBBOTTOM"),
"WINDOWDEPTH", "WINDOWDRAG", "BORDERLESS", "ACTIVATE" and
"NOCAREREFRESH". A special flag can be set: "BACKFILL". It implies
a call to BackFill() after opening the window. It sets the window's
background to the current requester-style background color.
call Quit(controlport)
This function closes the window, deallocates all resources and causes
the host to exit. CloseWindow(), Exit(), Quit() and Stop() are identical.
call ReadGadget(controlport, gadgetid)
This function will cause the gadget 'gadgetid' to send its message
text (after substitutions, of course).
call RectFill(controlport, xmin, ymin, xmax, ymax)
call RefreshGadgets(controlport)
call RemoveGadget(controlport, gadgetid)
call SetAPen(controlport, pennumber)
call SetBPen(controlport, pennumber)
call SetDrMd(controlport, mode)
mode can be any of JAM1, JAM2, INVERSVID or COMPLEMENT.
call SetDrPt(controlport, pattern)
pattern is interpreted as a long integer of which the bits form the
pattern.
call SetFont(controlport, FontName, FontSize)
call SetItem(controlport, menunumber, itemnuber, subitemnumber, action)
Given menu, item (and optionally subitem) numbers, perform action on
the menu item. Supported are ON and OFF, to set or clear the check mark.
call SetNotify(controlport, IDCMPclass, newnotifyport)
This function allows you to change the name of the NotifyPort that
message strings are sent to for a particular class of IDCMP events.
call SetReqColor(controlport, pentype, colornumber)
This function allows you to change the color number assigned to
one of the various pentypes. Currently the pentypes are: BLOCKPEN,
DETAILPEN, BACKGROUNDPEN, PROMPTPEN, BOXPEN, SHADOWPEN, OKAYPEN,
and CANCELPEN.
call SetOPen(controlport, pennumber)
call SetRGB4(controlport, pennumber, red, green, blue)
red, green and blue are values for the RGB content of the color to be
assigned to the pen. The values are taken mod 16.
call Stop(controlport)
This function closes the window, deallocates all resources and causes
the host to exit. CloseWindow(), Exit(), Quit() and Stop() are identical.
call Text(controlport, string)
call WindowText(controlport, text)
The string in text may contain \'s to indicate multiple lines of text.
call WindowToBack(controlport)
call WindowToFront(controlport)
call WritePixel(controlport, x, y)